docs(mcp-analytics): add experimental Ruby SDK sections by rafaeelaudibert · Pull Request #20022 · PostHog/posthog.com

rafaeelaudibert · 2026-09-09T02:22:31Z

Changes

Executive summary

This PR adds documentation for the new experimental and unsupported Ruby SDK for MCP analytics, PostHog::MCP. The SDK ships in the posthog-ruby gem (PostHog/posthog-ruby#269, merged). It changes three pages under contents/docs/mcp-analytics/ and nothing else. It does not add a page or a navigation entry, because MCP analytics documents each language as a section of the same page.

installation.mdx: adds Ruby to the requirements list and a ## Ruby section that mirrors the Python section. The section starts with an experimental callout. It covers install, PostHog::MCP.instrument, the posthog-rails shortcut, the options table, schema handling, event truncation, custom events, per-event $lib, stateless and multi-pod servers, flushing, and logging on stdio servers.
custom-servers.mdx: adds a ## Ruby section for PostHog::MCP::Client, the Ruby custom-dispatcher path, with the same experimental callout. It covers the tool list, the tool call (with input_schema: and model capture), the capture methods, caller attribution with the Rack middleware mint hook, and flushing.
sdk-v2.mdx: adds a ## Ruby section that explains how the Ruby SDK handles both protocol revisions and how callbacks read headers.

All new content marks the Ruby SDK as experimental and unsupported: PostHog does not give support for it, and the API and the captured event schema can change in a minor release.

The gem README says that these docs are the only source of truth for the SDK. Thus, I compared each Ruby section with the merged code (5397eae) and made these updates:

prepare_tool_call accepts input_schema:. If the tool declares its own context or llm_model field, the field stays in args.
Custom dispatchers can capture the model with prepare_tool_list(capture_model: true). In Ruby this is off by default. The TypeScript and Python helpers enable it by default.
The step 2 example no longer runs the tool a second time.
The installation page now includes the Ruby-specific notes from the gem README: composed schemas get no injected arguments, events are truncated to 32 KB, and analytics.capture keeps the request scope in spawned threads only on Ruby 3.2+.

Checks

Ran node scripts/fix-mdx.js and prettier on the three files.
Merged master and resolved the conflicts in custom-servers.mdx and installation.mdx.
Not run: the dev server (pnpm start). Please check the three pages in the Vercel preview build.

Checklist

I've read the docs and/or content style guides.
Words are spelled using American English
Use relative URLs for internal links
I've checked the pages added or changed in the Vercel preview build
If I moved a page, I added a redirect in vercel.json (no pages moved)

🤖 Generated with Claude Code

Add `## Ruby` sections to the MCP analytics installation, custom servers, and MCP SDK v2 pages for the new experimental `PostHog::MCP` integration in posthog-ruby, each opening with an experimental callout, and list Ruby in the installation requirements. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-09-09T02:22:42Z

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Sep 22, 2026 09:30PM

Changed pages

Page	Source
Instrumenting a custom server	`contents/docs/mcp-analytics/custom-servers.mdx`
Installing the MCP Analytics SDK	`contents/docs/mcp-analytics/installation.mdx`
MCP SDK v2	`contents/docs/mcp-analytics/sdk-v2.mdx`

rafaeelaudibert · 2026-09-09T02:22:48Z

Code PR: PostHog/posthog-ruby#269

github-actions · 2026-09-09T02:23:36Z

Vale prose linter → found 0 errors, 36 warnings, 1 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/mcp-analytics/custom-servers.mdx — 0 errors, 8 warnings, 1 suggestions

Line	Severity	Message	Rule
39:81	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	`PostHogDocs.DirectAddress`
110:120	warning	Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept.	`PostHogBase.ProductNames`
125:187	warning	'args' is a possible misspelling.	`PostHogBase.Spelling`
198:158	warning	'kwargs' is a possible misspelling.	`PostHogBase.Spelling`
202:323	warning	Use 'X' instead of 'x'.	`Vale.Terms`
209:158	warning	Use 'AI' instead of 'ai'.	`Vale.Terms`
209:162	warning	'Cowork' is a possible misspelling.	`PostHogBase.Spelling`
257:164	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	`PostHogBase.ProductNames`
357:52	warning	'OAuth' is a possible misspelling.	`PostHogBase.Spelling`

contents/docs/mcp-analytics/installation.mdx — 0 errors, 24 warnings, 0 suggestions

Line	Severity	Message	Rule
17:280	warning	'jlowin's' is a possible misspelling.	`PostHogBase.Spelling`
40:263	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
112:139	warning	Use the Oxford comma before 'and' or 'or' in a list of three or more items.	`PostHogBase.OxfordComma`
139:146	warning	'OAuth' is a possible misspelling.	`PostHogBase.Spelling`
147:313	warning	'untrusted' is a possible misspelling.	`PostHogBase.Spelling`
181:149	warning	Use 'MCP' instead of 'mcp'.	`Vale.Terms`
181:178	warning	'mutator' is a possible misspelling.	`PostHogBase.Spelling`
185:130	warning	'mutator' is a possible misspelling.	`PostHogBase.Spelling`
207:5	warning	'Streamable' is a possible misspelling.	`PostHogBase.Spelling`
220:5	warning	'If you must stream (SSE)' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`
254:180	warning	'jlowin's' is a possible misspelling.	`PostHogBase.Spelling`
258:168	warning	Use 'X' instead of 'x'.	`Vale.Terms`
259:47	warning	Use 'X' instead of 'x'.	`Vale.Terms`
260:4	warning	'jlowin's' is a possible misspelling.	`PostHogBase.Spelling`
315:38	warning	'jlowin's' is a possible misspelling.	`PostHogBase.Spelling`
360:263	warning	Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept.	`PostHogBase.ProductNames`
362:45	warning	Use 'PostHog' instead of 'posthog'.	`Vale.Terms`
374:180	warning	'Streamable' is a possible misspelling.	`PostHogBase.Spelling`
420:83	warning	'stdout' is a possible misspelling.	`PostHogBase.Spelling`
460:27	warning	'stdout' is a possible misspelling.	`PostHogBase.Spelling`
460:168	warning	'misconfiguration' is a possible misspelling.	`PostHogBase.Spelling`
460:200	warning	'stderr' is a possible misspelling.	`PostHogBase.Spelling`
460:246	warning	'stdout' is a possible misspelling.	`PostHogBase.Spelling`
523:47	warning	Use 'X' instead of 'x'.	`Vale.Terms`

contents/docs/mcp-analytics/sdk-v2.mdx — 0 errors, 4 warnings, 0 suggestions

Line	Severity	Message	Rule
56:146	warning	Use 'X' instead of 'x'.	`Vale.Terms`
66:46	warning	'jlowin's' is a possible misspelling.	`PostHogBase.Spelling`
66:119	warning	Use 'X' instead of 'x'.	`Vale.Terms`
122:4	warning	'MCP Apps' heading should be in sentence case, and product names should be capitalized.	`PostHogBase.SentenceCase`

Vale style fixes limited to the newly added Ruby sections. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Explain the custom-dispatcher path step by step and drop references to the other SDKs so the Ruby sections read on their own. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

rafaeelaudibert · 2026-09-09T02:35:10Z

Vale: fixed en dashes and ID in the added Ruby sections (2072f95). The remaining findings are on pre-existing lines of these pages and left as is.

github-actions · 2026-09-09T02:45:52Z

Bundle report

Total JS (gzip)

8.67 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ `app`	18.65 MiB (no change)	report-only	2070

Largest modules in the app closure

Module	Size
`./src/data/mcp-tools.json`	1186.4 KiB
`css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css`	770.8 KiB
`./src/components/Stickers/Stickers.tsx`	696.4 KiB
`./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js`	481.4 KiB
`./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs`	480.8 KiB
`./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules`	395.1 KiB
`./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs`	385.7 KiB
`./src/hooks/useCustomers.tsx + 55 modules`	372.5 KiB
`./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js`	354.8 KiB
`./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules`	351.4 KiB
`./src/components/ProductComparisonTable/index.tsx + 127 modules`	310.3 KiB
`./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js`	281.9 KiB
`./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs`	281.7 KiB
`./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs`	275.6 KiB
`./src/components/SearchUI/index.tsx + 87 modules`	273.7 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

…nt hook The MCP analytics team doesn't maintain the Ruby SDK, so the callouts now say it is not officially supported and point at TypeScript or Python for a supported one. The custom-dispatcher section covers `env['posthog_mcp.mint']`, since the Rack middleware no longer parses request bodies to mint a session. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Document input_schema: on prepare_tool_call, model capture for custom dispatchers, composed-schema handling, 32 KB truncation, and the Ruby 3.2 scope rule for analytics.capture. Stop the step 2 example from running the tool a second time. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…ruby # Conflicts: # contents/docs/mcp-analytics/custom-servers.mdx # contents/docs/mcp-analytics/installation.mdx

rafaeelaudibert self-assigned this Sep 9, 2026

github-project-automation Bot added this to PostHog.com planning Sep 9, 2026

github-project-automation Bot moved this to Backlog in PostHog.com planning Sep 9, 2026

github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Sep 9, 2026

rafaeelaudibert mentioned this pull request Sep 9, 2026

feat: experimental MCP analytics (PostHog::MCP) for the Ruby mcp gem PostHog/posthog-ruby#269

Merged

5 tasks

rafaeelaudibert requested review from gesh and lucasheriques September 9, 2026 02:28

rafaeelaudibert and others added 2 commits September 8, 2026 23:30

docs(mcp-analytics): use en dashes and ID in the Ruby sections

06616c3

Vale style fixes limited to the newly added Ruby sections. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs(mcp-analytics): make the Ruby sections self-contained

2072f95

Explain the custom-dispatcher path step by step and drop references to the other SDKs so the Ruby sections read on their own. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

posthog Bot mentioned this pull request Sep 16, 2026

docs(mcp-analytics): add a bring-your-own-SDK install path #20249

Draft

5 tasks

rafaeelaudibert enabled auto-merge (squash) September 22, 2026 21:16

Merge remote-tracking branch 'origin/master' into docs/mcp-analytics-…

10fc0c4

…ruby # Conflicts: # contents/docs/mcp-analytics/custom-servers.mdx # contents/docs/mcp-analytics/installation.mdx

rafaeelaudibert merged commit d50d337 into master Sep 22, 2026
21 checks passed

rafaeelaudibert deleted the docs/mcp-analytics-ruby branch September 22, 2026 21:30

github-project-automation Bot moved this from Backlog to Done in PostHog.com planning Sep 22, 2026

Navigation Menu

docs(mcp-analytics): add experimental Ruby SDK sections - #20022

docs(mcp-analytics): add experimental Ruby SDK sections#20022
rafaeelaudibert merged 6 commits into
masterfrom
docs/mcp-analytics-ruby

rafaeelaudibert commented Sep 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

rafaeelaudibert commented Sep 9, 2026

Uh oh!

github-actions Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

rafaeelaudibert commented Sep 9, 2026

Uh oh!

github-actions Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

rafaeelaudibert commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Executive summary

Checks

Checklist

Uh oh!

github-actions Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Changed pages

Uh oh!

rafaeelaudibert commented Sep 9, 2026

Uh oh!

github-actions Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rafaeelaudibert commented Sep 9, 2026

Uh oh!

github-actions Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle report

Total JS (gzip)

Eager graph (modules shipped in each entrypoint's initial chunks)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

rafaeelaudibert commented Sep 9, 2026 •

edited

Loading

github-actions Bot commented Sep 9, 2026 •

edited

Loading

github-actions Bot commented Sep 9, 2026 •

edited

Loading

github-actions Bot commented Sep 9, 2026 •

edited

Loading